home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / ref / postquel / copy < prev    next >
Encoding:
Text File  |  1992-08-27  |  4.7 KB  |  164 lines
  1. .\" XXX standard disclaimer belongs here....
  2. .\" $Header: /private/postgres/ref/postquel/RCS/copy,v 1.13 1992/07/14 05:54:17 ptong Exp $
  3. .SP COPY COMMANDS 6/14/90
  4. .XA 2 Copy
  5. .uh NAME
  6. .lp
  7. copy \*- copy data to or from a class from or to a \*(UU file.
  8. .uh SYNOPSIS
  9. .lp
  10. .(l
  11. \fBcopy\fR [\fBbinary\fR] classname direction ( "filename" | \fBstdin\fR | \fBstdout\fR )
  12. .)l
  13. .uh DESCRIPTION
  14. .lp
  15. .b Copy
  16. moves data between \*(PP classes and standard \*(UU files.
  17. The keyword
  18. .b binary
  19. change the behavior of field formatting,
  20. as described below.
  21. .i Classname
  22. is the name of an existing class.
  23. .i Direction
  24. is either 
  25. .b to
  26. or 
  27. .b from .
  28. .i Filename
  29. is the \*(UU pathname of the file.  In place of a filename, stdin and stdout
  30. can be used so that input to
  31. .b copy
  32. can be written by a LIBPQ application and 
  33. output from the
  34. .b copy
  35. command can be read by a LIBPQ application.
  36. The 
  37. .b binary
  38. keyword will force all data to be stored/read as binary objects rather than
  39. as ASCII text.  It is somewhat faster than the normal
  40. .b copy
  41. command, but is not generally portable, and the files generated are somewhat
  42. larger, although this factor is highly dependent on the data itself.
  43. .uh FORMAT OF OUTPUT FILES
  44. .lp
  45. When
  46. .b copy
  47. is used without the
  48. .b binary
  49. keyword, the file generated will have each instance on a line, with each
  50. attribute separated by tabs (\t).  Embedded tabs will be preceeded by a
  51. backslash character (\\).  The attribute values themselves are strings generated
  52. by the output function associated with each attribute type.  The output
  53. function for a type should not try to generate the backslash character - this
  54. will be handled by 
  55. .b copy
  56. itself.
  57. .lp
  58. Note that on input to 
  59. .b copy
  60. backslashes are considered to be special control characters, and should be
  61. doubled if you want to embed a backslash, ie, the string "12\\19\\88" will be
  62. converted by
  63. .b copy
  64. to "12\19\88".  The actual format for each instance is
  65. .lp
  66. <attr1><tab><attr2><tab>...<tab><attrn><newline>
  67. .lp
  68. If 
  69. .b copy
  70. is sending its output to standard output instead of a file, it will send a
  71. period (.) followed immediately by a newline, on a line by themselves, when
  72. it is done.  Similarly, if
  73. .b copy
  74. is reading from standard input, it will expect a period (.) followed by a
  75. newline, as the first two characters on a line, to denote end-of-file.
  76. However,
  77. .b copy
  78. will terminate (followed by the backend itself) if a true EOF is encountered.
  79. .lp
  80. .b NULL
  81. attributes are handled simply as null strings, that is, consecutive tabs in
  82. the input file denote a 
  83. .b NULL
  84. attribute.
  85. .lp
  86. In the case of
  87. .b copy
  88. .b binary,
  89. the first four bytes in the file will be the number of instances in the file.
  90. If this number is
  91. .i zero,
  92. the
  93. .b copy
  94. .b binary
  95. command will read until end of file is encountered.  Otherwise, it will
  96. .i stop
  97. reading when this number of instances has been read.  Remaining data in the
  98. file will be ignored.
  99. .lp
  100. The format for each instance in the file is as follows.  Note that this format
  101. must be followed
  102. .i EXACTLY.
  103. Unsigned four byte integer quantities are called uint32 in the below
  104. description.
  105. .lp
  106. uint32 totallength (not including itself),
  107. .lp
  108. uint32 number of null attributes
  109. .lp
  110. [uint32 attribute number of first null attribute
  111. .lp
  112. ...
  113. .lp
  114. uint32 attribute number of nth null attribute],
  115. .lp
  116. <data>
  117. .lp
  118. .i "Alignment of binary data"
  119. .lp
  120. On Sun 3's, 2 byte attributes are aligned on two-byte boundaries, and all
  121. larger attributes are aligned on four-byte boundaries.  Character attributes
  122. are aligned on single-byte boundaries.  On other machines, all attributes
  123. larger than 1 byte are aligned on four-byte boundaries.  Note that variable
  124. length attributes are preceeded by the attribute's length; arrays are simply
  125. contiguous streams of the array element type.
  126. .lp
  127. .uh "SEE ALSO"
  128. .lp
  129. append(commands), create(commands), vacuum(commands), libpq.
  130. .uh BUGS
  131. .lp
  132. .A Files 
  133. used as arguments to the
  134. .b copy
  135. command must reside on or be accessable to the
  136. the database server machine by being either on local disks or a networked
  137. file system.
  138. .lp
  139. .b Copy
  140. stops operation at the first error.
  141. This should not lead to problems
  142. in the event of a
  143. .b copy
  144. .b from,
  145. but the target relation will, of course, be partially modified
  146. in a
  147. .b copy 
  148. .b to.
  149. The ``vacuum'' query should be used to clean up after a
  150. failed copy.
  151. .lp
  152. Because \*(PP operates out of a different directory 
  153. than the user's working directory at the time \*(PP is invoked,
  154. the result of copying to a file 
  155. .q "foo"
  156. (without additional path information)
  157. may yield unexpected results for the naive user.
  158. The full pathname should be used when specifying files to be copied.
  159. .lp
  160. .b Copy
  161. has virtually no error checking, and a malformed input file will likely cause
  162. the backend to crash.  Humans should avoid using copy for input whenever
  163. possible.
  164.